Kubernetes Operator开发超详细指南

一、前言:什么是 Operator?

1.1 Operator 的本质

想象一下,如果你有一个复杂的应用,比如数据库集群,你需要手动执行很多操作:部署、配置、升级、备份、故障恢复等等。这些操作需要专业的运维知识,而且容易出错。

Operator 就是为了解决这个问题而生的。它是一种 Kubernetes 扩展,能够将特定应用的运维知识编码到软件中,实现应用的自动化管理。

简单来说,Operator = 自定义资源(CRD) + 控制器(Controller) + 应用运维知识

1.2 为什么需要 Operator?

1.3 Operator 的工作原理

Operator 的工作基于 Kubernetes 的控制器模式,核心是一个调谐循环(Reconcile Loop):

  1. 观察期望状态:读取自定义资源(CR)中定义的期望状态(Spec)
  2. 观察实际状态:检查集群中应用的实际状态
  3. 调谐:如果实际状态与期望状态不一致,执行操作使它们一致

这个过程会持续运行,确保应用始终保持在期望的状态。

二、准备工作:环境搭建

2.1 安装必要工具

2.2 创建本地 Kubernetes 集群

参考 基于Kind搭建测试集群 创建一个本地高可用 Kubernetes 集群,用于开发和测试。

集群配置:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  apiServerAddress: "192.168.1.13"
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 6443
    hostPort: 6443
    listenAddress: "192.168.1.13"
    protocol: tcp
- role: control-plane
- role: control-plane
- role: worker
- role: worker
- role: worker

创建集群:

sudo kind create cluster --config=kind-config.yaml --name my-test --image kindest/node:v1.34.0 --retain
sudo kubectl cluster-info --context kind-my-test

2.3 配置 Go 环境变量

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct

三、项目初始化:创建 Operator 项目

3.1 初始化项目结构

mkdir -p ~/workspace/operator/myapp-operator
cd ~/workspace/operator/myapp-operator

kubebuilder init --domain example.com --repo myapp-operator

3.2 查看项目结构

.
├── cmd/                # 命令行入口
├── config/             # 配置文件
├── hack/               # 脚本文件
├── test/               # 测试文件
├── Dockerfile          # Docker构建文件
├── Makefile            # 构建脚本
├── PROJECT             # 项目元数据
├── go.mod              # Go模块文件
└── go.sum              # Go依赖校验文件

3.3 创建 API 和控制器

kubebuilder create api --group apps --version v1 --kind MyApp

执行时 kubebuilder 会提示是否创建资源和控制器,都选择 y。

新增的关键文件:

四、CRD 定义:定义自定义资源

4.1 理解 CRD 结构

CRD(Custom Resource Definition)是自定义资源的定义,它扩展了 Kubernetes API,允许我们创建和管理自定义资源。

在 api/v1/myapp_types.go 文件中,kubebuilder 生成的默认结构:

package v1

import (
   metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// MyAppSpec defines the desired state of MyApp
type MyAppSpec struct {
   // +optional
   Foo *string `json:"foo,omitempty"`
}

// MyAppStatus defines the observed state of MyApp.
type MyAppStatus struct {
   // +listType=map
   // +listMapKey=type
   // +optional
   Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// MyApp is the Schema for the myapps API
type MyApp struct {
   metav1.TypeMeta   `json:",inline"`
   metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`
   Spec              MyAppSpec   `json:"spec"`
   Status            MyAppStatus `json:"status,omitempty,omitzero"`
}

// +kubebuilder:object:root=true

// MyAppList contains a list of MyApp
type MyAppList struct {
   metav1.TypeMeta `json:",inline"`
   metav1.ListMeta `json:"metadata,omitempty"`
   Items           []MyApp `json:"items"`
}

func init() {
   SchemeBuilder.Register(&MyApp{}, &MyAppList{})
}

4.2 修改 CRD 定义

修改 MyApp 资源的定义,创建一个简单的应用管理资源,用于部署和管理 Nginx 应用:

// MyAppSpec defines the desired state of MyApp
type MyAppSpec struct {
	// 应用名称
	AppName string `json:"appName,omitempty"`

	// 副本数
	Replicas int32 `json:"replicas,omitempty"`

	// 镜像信息
	Image string `json:"image,omitempty"`

	// 端口信息
	Port int32 `json:"port,omitempty"`
}

// MyAppStatus defines the observed state of MyApp
type MyAppStatus struct {
	// 部署状态
	Status string `json:"status,omitempty"`

	// 可用副本数
	AvailableReplicas int32 `json:"availableReplicas,omitempty"`

	// 服务URL
	ServiceURL string `json:"serviceURL,omitempty"`
}

4.3 生成代码和 CRD 清单

# 生成 DeepCopy 方法
make generate

# 生成 CRD 清单文件(config/crd/bases/)和 RBAC 规则(config/rbac/)
make manifests

五、控制器开发:编写调谐逻辑

5.1 理解控制器结构

控制器是 Operator 的核心,负责监控自定义资源的变化,并执行调谐逻辑。kubebuilder 生成的默认结构:

// MyAppReconciler reconciles a MyApp object
type MyAppReconciler struct {
   client.Client
   Scheme *runtime.Scheme
}

// +kubebuilder:rbac:groups=apps.example.com,resources=myapps,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=apps.example.com,resources=myapps/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=apps.example.com,resources=myapps/finalizers,verbs=update

func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
   _ = logf.FromContext(ctx)
   // TODO(user): your logic here
   return ctrl.Result{}, nil
}

func (r *MyAppReconciler) SetupWithManager(mgr ctrl.Manager) error {
   return ctrl.NewControllerManagedBy(mgr).
      For(&appsv1.MyApp{}).
      Named("myapp").
      Complete(r)
}

5.2 编写调谐逻辑

实现 Reconcile 函数的逻辑,目标:

  1. 当创建 MyApp 资源时,自动创建对应的 Deployment 和 Service
  2. 当更新 MyApp 资源时,自动更新对应的 Deployment 和 Service
  3. 当删除 MyApp 资源时,自动删除对应的 Deployment 和 Service(通过 OwnerReference)
  4. 更新 MyApp 资源的状态,反映实际的部署情况
import (
	"context"
	"fmt"

	"k8s.io/apimachinery/pkg/api/errors"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/types"
	appsv1 "k8s.io/api/apps/v1"
	corev1 "k8s.io/api/core/v1"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/log"

	apps "myapp-operator/api/v1"
)

func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	logger := log.FromContext(ctx)
	logger.Info("开始处理MyApp资源", "name", req.Name, "namespace", req.Namespace)

	// 1. 获取MyApp资源
	var myapp apps.MyApp
	if err := r.Get(ctx, req.NamespacedName, &myapp); err != nil {
		if errors.IsNotFound(err) {
			logger.Info("MyApp资源不存在,可能已被删除")
			return ctrl.Result{}, nil
		}
		return ctrl.Result{}, err
	}

	// 2. 处理Deployment
	deploymentName := fmt.Sprintf("%s-deployment", myapp.Name)
	deployment := &appsv1.Deployment{
		ObjectMeta: metav1.ObjectMeta{
			Name:      deploymentName,
			Namespace: myapp.Namespace,
			Labels:    map[string]string{"app": myapp.Name},
		},
		Spec: appsv1.DeploymentSpec{
			Replicas: &myapp.Spec.Replicas,
			Selector: &metav1.LabelSelector{
				MatchLabels: map[string]string{"app": myapp.Name},
			},
			Template: corev1.PodTemplateSpec{
				ObjectMeta: metav1.ObjectMeta{
					Labels: map[string]string{"app": myapp.Name},
				},
				Spec: corev1.PodSpec{
					Containers: []corev1.Container{
						{
							Name:  myapp.Name,
							Image: myapp.Spec.Image,
							Ports: []corev1.ContainerPort{
								{ContainerPort: myapp.Spec.Port},
							},
						},
					},
				},
			},
		},
	}

	// 设置OwnerReference,确保Deployment随MyApp资源一起删除
	if err := ctrl.SetControllerReference(&myapp, deployment, r.Scheme); err != nil {
		return ctrl.Result{}, err
	}

	// 检查Deployment是否存在
	var existingDeployment appsv1.Deployment
	err := r.Get(ctx, types.NamespacedName{Name: deploymentName, Namespace: myapp.Namespace}, &existingDeployment)
	if err != nil {
		if errors.IsNotFound(err) {
			logger.Info("创建Deployment", "name", deploymentName)
			if err := r.Create(ctx, deployment); err != nil {
				return ctrl.Result{}, err
			}
		} else {
			return ctrl.Result{}, err
		}
	} else {
		logger.Info("更新Deployment", "name", deploymentName)
		existingDeployment.Spec = deployment.Spec
		if err := r.Update(ctx, &existingDeployment); err != nil {
			return ctrl.Result{}, err
		}
	}

	// 3. 处理Service
	serviceName := fmt.Sprintf("%s-service", myapp.Name)
	service := &corev1.Service{
		ObjectMeta: metav1.ObjectMeta{
			Name:      serviceName,
			Namespace: myapp.Namespace,
			Labels:    map[string]string{"app": myapp.Name},
		},
		Spec: corev1.ServiceSpec{
			Selector: map[string]string{"app": myapp.Name},
			Ports: []corev1.ServicePort{
				{Port: myapp.Spec.Port, Protocol: corev1.ProtocolTCP},
			},
			Type: corev1.ServiceTypeClusterIP,
		},
	}

	if err := ctrl.SetControllerReference(&myapp, service, r.Scheme); err != nil {
		return ctrl.Result{}, err
	}

	var existingService corev1.Service
	err = r.Get(ctx, types.NamespacedName{Name: serviceName, Namespace: myapp.Namespace}, &existingService)
	if err != nil {
		if errors.IsNotFound(err) {
			logger.Info("创建Service", "name", serviceName)
			if err := r.Create(ctx, service); err != nil {
				return ctrl.Result{}, err
			}
		} else {
			return ctrl.Result{}, err
		}
	} else {
		logger.Info("更新Service", "name", serviceName)
		existingService.Spec = service.Spec
		if err := r.Update(ctx, &existingService); err != nil {
			return ctrl.Result{}, err
		}
	}

	// 4. 更新MyApp资源的状态
	if err := r.Get(ctx, types.NamespacedName{Name: deploymentName, Namespace: myapp.Namespace}, &existingDeployment); err != nil {
		return ctrl.Result{}, err
	}
	if err := r.Get(ctx, types.NamespacedName{Name: serviceName, Namespace: myapp.Namespace}, &existingService); err != nil {
		return ctrl.Result{}, err
	}

	myapp.Status.Status = "Running"
	myapp.Status.AvailableReplicas = existingDeployment.Status.AvailableReplicas
	myapp.Status.ServiceURL = fmt.Sprintf("%s.%s.svc.cluster.local:%d",
		existingService.Name, existingService.Namespace, myapp.Spec.Port)

	if err := r.Status().Update(ctx, &myapp); err != nil {
		return ctrl.Result{}, err
	}

	logger.Info("MyApp资源处理完成", "name", myapp.Name)
	return ctrl.Result{}, nil
}

5.3 注册控制器

确保控制器在 Manager 中正确注册(cmd/main.go):

// 注册MyApp控制器
if err = (&controller.MyAppReconciler{
    Client: mgr.GetClient(),
    Scheme: mgr.GetScheme(),
}).SetupWithManager(mgr); err != nil {
    setupLog.Error(err, "unable to create controller", "controller", "MyApp")
    os.Exit(1)
}

六、部署和测试:验证 Operator 功能

6.1 安装 CRD 并本地运行

# 安装 CRD 到集群
make install

# 本地运行控制器(开发调试用)
export ENABLE_WEBHOOKS=false
make run

6.2 创建测试资源

apiVersion: apps.example.com/v1
kind: MyApp
metadata:
  name: myapp-test
  namespace: default
spec:
  appName: nginx-test
  replicas: 2
  image: nginx:latest
  port: 80
kubectl apply -f myapp-test.yaml

6.3 验证部署结果

kubectl get myapp
kubectl describe myapp myapp-test
kubectl get deployment
kubectl get pods
kubectl get service

预期结果:

6.4 更新和删除测试

更新副本数:

# 修改 replicas 为 3 后
kubectl apply -f myapp-test.yaml
kubectl get pods  # 应该看到 3 个 Pod

删除资源:

kubectl delete -f myapp-test.yaml
kubectl get deployment  # 所有相关资源应被级联删除

七、构建和部署:将 Operator 部署到集群

7.1 构建镜像

make docker-build IMG=myapp-operator:v1.0.0

7.2 加载镜像到 kind 集群

kind load docker-image myapp-operator:v1.0.0 --name my-test

7.3 部署到集群

make deploy IMG=myapp-operator:v1.0.0

7.4 验证部署

kubectl get deployment -n myapp-operator-system
kubectl get pods -n myapp-operator-system
kubectl get service -n myapp-operator-system

八、常见问题和解决方案

8.1 连接集群失败

错误:dial tcp 127.0.0.1:8080: connect: connection refused

解决:确保 kubeconfig 文件正确配置。对于 kind 集群:

kind export kubeconfig --name=my-test --kubeconfig=$HOME/.kube/config
kubectl cluster-info

8.2 CRD 注解过长

错误:metadata.annotations: Too long: must have at most 262144 bytes

解决:修改 Makefile,在 manifests 命令中添加 crd:maxDescLen=0:

.PHONY: manifests
manifests: controller-gen
	$(CONTROLLER_GEN) rbac:roleName=manager-role crd:maxDescLen=0 webhook paths="./..." output:crd:artifacts:config=config/crd/bases

8.3 Webhook 证书问题

错误:failed to get webhook server certificate

解决:

8.4 控制器启动失败

错误:unable to create controller

排查步骤:

  1. 检查控制器代码语法
  2. 检查依赖是否正确安装
  3. 检查 RBAC 权限配置
  4. 查看日志:kubectl logs -n myapp-operator-system deployment/myapp-operator-controller-manager

九、总结

通过本指南,我们学习了如何从零开始开发一个 Kubernetes Operator:

资源推荐